<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Resource Adapters and Contracts - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level3"><a href="bncji.html">Resources and JNDI Naming</a></p>
<p class="toc level3"><a href="bncjj.html"><tt>DataSource</tt> Objects and Connection Pools</a></p>
<p class="toc level3"><a href="bncjk.html">Resource Injection</a></p>
<p class="toc level4"><a href="bncjk.html#bncjl">Field-Based Injection</a></p>
<p class="toc level4"><a href="bncjk.html#bncjm">Method-Based Injection</a></p>
<p class="toc level4"><a href="bncjk.html#bncjn">Class-Based Injection</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Resource Adapters and Contracts</a></p>
<p class="toc level4"><a href="#gipgy">Management Contracts</a></p>
<p class="toc level5"><a href="#gipht">Lifecycle Management</a></p>
<p class="toc level5"><a href="#gipig">Work Management Contract</a></p>
<p class="toc level4 tocsp"><a href="#gipmk">Generic Work Context Contract</a></p>
<p class="toc level4"><a href="#gkcki">Outbound and Inbound Contracts</a></p>
</div>
<p class="toc level3 tocsp"><a href="girdd.html">Metadata Annotations</a></p>
<p class="toc level3"><a href="gipju.html">Common Client Interface</a></p>
<p class="toc level3"><a href="bncjw.html">Further Information about Resources</a></p>
<p class="toc level2 tocsp"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bncjk.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="girdd.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gipgl"></a><h2>Resource Adapters and Contracts</h2>
<a name="indexterm-2288"></a><p>A resource adapter is a Java EE component that implements the Java
EE Connector Architecture for a specific EIS. Examples of EISs include enterprise resource planning,
mainframe transaction processing, and database systems. As illustrated in <a href="#gjtzo">Figure&nbsp;44-1</a>, the resource adapter facilitates
communication between a Java EE application and an EIS.</p>

<a name="gjtzo"></a><p class="caption">Figure&nbsp;44-1 Resource Adapters</p><img src="figures/connector-accessingEIS.gif" alt="Resource Adapter Contracts"></img><p>Stored in a Resource Adapter Archive (RAR) file, a resource adapter can be
deployed on any Java EE server, much like a Java EE application.
A RAR file may be contained in an Enterprise Archive (EAR) file, or
it may exist as a separate file.</p>

<p>A resource adapter is analogous to a JDBC driver. Both provide a
standard API through which an application can access a resource that is outside
the Java EE server. For a resource adapter, the target system is an
EIS; for a JDBC driver, it is a DBMS. Resource adapters and JDBC
drivers are rarely created by application developers. In most cases, both types of
software are built by vendors that sell tools, servers, or integration software.</p>

<p>The resource adapter mediates communication between the Java EE server and the EIS
by means of contracts. The application contract defines the API through which a
Java EE component, such as an enterprise bean, accesses the EIS. This API
is the only view that the component has of the EIS. The
system contracts link the resource adapter to important services that are managed by the
Java EE server. The resource adapter itself and its system contracts are transparent
to the Java EE component.</p>



<a name="gipgy"></a><h3>Management Contracts</h3>
<p>The Java EE Connector Architecture defines system contracts that enable resource adapter lifecycle
and thread management.</p>



<a name="gipht"></a><h4>Lifecycle Management</h4>
<p>The Connector Architecture specifies a lifecycle management contract that allows an application server
to manage the lifecycle of a resource adapter. This contract provides a mechanism
for the application server to bootstrap a resource adapter instance during the deployment
or application server startup. This contract also provides a means for the application
server to notify the resource adapter instance when it is undeployed or when
an orderly shutdown of the application server takes place.</p>



<a name="gipig"></a><h4>Work Management Contract</h4>
<p>The Connector Architecture work management contract ensures that resource adapters use threads in
the proper, recommended manner. This contract also enables an application server to manage
threads for resource adapters.</p>

<p>Resource adapters that improperly use threads can jeopardize the entire application server environment.
For example, a resource adapter might create too many threads or might not
properly release threads it has created. Poor thread handling inhibits application server shutdown
and impacts the application server&rsquo;s performance because creating and destroying threads are expensive operations.</p>

<p>The work management contract establishes a means for the application server to pool
and reuse threads, similar to pooling and reusing connections. By adhering to this
contract, the resource adapter does not have to manage threads itself. Instead, the
resource adapter has the application server create and provide needed threads. When it
is finished with a given thread, the resource adapter returns the thread to
the application server. The application server manages the thread, either returning it to
a pool for later reuse or destroying it. Handling threads in this manner
results in increased application server performance and more efficient use of resources.</p>

<p>In addition to moving thread management to the application server, the Connector Architecture
provides a flexible model for a resource adapter that uses threads.</p>


<ul><li><p>The requesting thread can choose to block (stop its own execution) until the work thread completes.</p>

</li>
<li><p>The requesting thread can block while it waits to get the work thread. When the application server provides a work thread, the requesting thread and the work thread execute in parallel.</p>

</li>
<li><p>The resource adapter can opt to submit the work for the thread to a queue. The thread executes the work from the queue at some later point. The resource adapter continues its own execution from the point it submitted the work to the queue, no matter when the thread executes it.</p>

</li></ul>
<p>With the latter two approaches, the submitting thread and the work thread may
execute simultaneously or independently. For these approaches, the contract specifies a listener mechanism
to notify the resource adapter that the thread has completed its operation. The
resource adapter can also specify the execution context for the thread, and the
work management contract controls the context in which the thread executes.</p>



<a name="gipmk"></a><h3>Generic Work Context Contract</h3>
<p>The work management contract between the application server and a resource adapter enables
a resource adapter to do a task, such as communicating with the EIS
or delivering messages, by delivering <tt>Work</tt> instances for execution.</p>

<p>A generic work context contract enables a resource adapter to control the contexts
in which the <tt>Work</tt> instances that it submits are executed by the application
server&rsquo;s <tt>WorkManager</tt>. A generic work context mechanism also enables an application server to
support new message inflow and delivery schemes. It also provides a richer contextual
<tt>Work</tt> execution environment to the resource adapter while still maintaining control over concurrent
behavior in a managed environment.</p>

<p>The generic work context contract standardizes the transaction context and the security context.</p>



<a name="gkcki"></a><h3>Outbound and Inbound Contracts</h3>
<p>The Connector Architecture defines the following outbound contracts, system-level contracts between an application
server and an EIS that enable outbound connectivity to an EIS.</p>


<ul><li><p>The connection management contract supports connection pooling, a technique that enhances application performance and scalability. Connection pooling is transparent to the application, which simply obtains a connection to the EIS.</p>

</li>
<li><p>The transaction management contract extends the connection management contract and provides support for management of both local and XA transactions.</p>

<p>A local transaction is limited in scope to a single EIS system, and the EIS resource manager itself manages such transaction. An XA transaction or global transaction can span multiple resource managers. This form of transaction requires transaction coordination by an external transaction manager, typically bundled with an application server. A transaction manager uses a two-phase commit protocol to manage a transaction that spans multiple resource managers or EISs, and uses one-phase commit optimization if only one resource manager is participating in an XA transaction.</p>

</li>
<li><p>The security management contract provides mechanisms for authentication, authorization, and secure communication between a Java EE server and an EIS to protect the information in the EIS.</p>

<p>A work security map matches EIS identities to the application server domain&rsquo;s identities.</p>

</li></ul>
<p>Inbound contracts are system contracts between a Java EE server and an EIS
that enable inbound connectivity from the EIS: pluggability contracts for message providers and
contracts for importing transactions.</p>


         </div>
         <div class="navigation">
             <a href="bncjk.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="girdd.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

